Workflow

1. Overview

This Workflow module allows you to define, manage, and automate document approval processes in ERPNext. It includes state transitions, role-based permissions, and docstatus controls, integrated with backend validation and frontend visual tools (Workflow Builder).

2. Key Features

Visual Workflow Builder (drag-and-drop interface)
Support for custom workflow states and transitions
Auto creation of hidden state fields in documents
Role-based action control
Email notifications on transitions
Bulk workflow approval handling
Enforcement of valid state transitions

3. Pre-Requisites

Must have System Manager role to create or edit Workflows.
Target DocType should not be Single or Child Table.
The document must include a field for workflow state (workflow_state_field) or it will be created automatically.

4. Step-by-Step Usage

Navigate to: Workflow > New.
Fill in Basic Info:
- Workflow Name
- Document Type
Set States:
- Define each workflow state
- Assign docstatus: 0 (Saved), 1 (Submitted), 2 (Cancelled)
Set Transitions:
- Define which state can move to another
- Assign user roles and actions
Activate Workflow:
- Enable "Is Active" to apply it (automatically deactivates others for the same DocType).
Use Workflow Builder (Optional):
- Access visual editor for design and positioning of states.
Save and Test:
- Test transitions on the respective document type.

5. Script Customizations

Python (workflow.py):
- apply_workflow: Applies transitions and updates docstatus.
- get_transitions: Fetches permitted transitions per user role.
- bulk_workflow_approval: Background processing for mass updates.
Client JS (workflow.js):
- Enhances form UI, shows orphaned states, integrates with builder.
- Adds validation for transitions and roles.
DocType JSON (workflow.json):
- Controls schema, field definitions, and default behavior.

6. Troubleshooting (Common Errors and Resolutions)

Error Message	Reason	Resolution
"Workflow State not set"	Missing workflow_state value	Ensure workflowstatefield is set in the document
"Cannot change state of Cancelled Document"	Transition from docstatus=2 attempted	Remove invalid transition in configuration
"Submitted Document cannot be converted back to draft"	Invalid transition 1 → 0	Update transition rules
"Workflow must have at least one state and transition"	Missing essential definitions	Define at least one state and one transition
"Not a valid Workflow Action"	Action not permitted for user or state	Check role assignments in the transition

7. User Roles and Permissions

Only roles assigned in transitions can perform workflow actions.
System Manager can create or edit workflows.
Self approval restriction: If allow_self_approval is not checked, users cannot approve their own documents.

8. Key Notes

Workflows are docstatus-aware: transitions enforce legal status changes.
The system automatically deactivates old workflows when a new one is activated for the same DocType.
Transition conditions can be defined using Python expressions (evaluated safely).
Orphaned states are detected and shown to the user for correction.

9. What Business Process Pain Point Does It Help Remove

This module eliminates manual and inconsistent approval processes by introducing:

Controlled document status flow
Role-based transitions
Audit trail of state changes
Automated field updates and notifications

It ensures compliance, transparency, and operational efficiency across document-driven workflows in the ERP system.